home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 2002 November
/
SGI Freeware 2002 November - Disc 1.iso
/
dist
/
fw_elisp-manual-21.idb
/
usr
/
freeware
/
info
/
elisp-31.z
/
elisp-31
Wrap
Text File
|
2002-07-08
|
50KB
|
1,137 lines
This is elisp, produced by makeinfo version 4.0f from ./elisp.texi.
INFO-DIR-SECTION Editors
START-INFO-DIR-ENTRY
* Elisp: (elisp). The Emacs Lisp Reference Manual.
END-INFO-DIR-ENTRY
This Info file contains edition 2.8 of the GNU Emacs Lisp Reference
Manual, corresponding to Emacs version 21.2.
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
2000, 2001, 2002 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Copying", with the Front-Cover texts being "A
GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of
the license is included in the section entitled "GNU Free Documentation
License".
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
File: elisp, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
Comparing Text
==============
This function lets you compare portions of the text in a buffer,
without copying them into strings first.
- Function: compare-buffer-substrings buffer1 start1 end1 buffer2
start2 end2
This function lets you compare two substrings of the same buffer
or two different buffers. The first three arguments specify one
substring, giving a buffer and two positions within the buffer.
The last three arguments specify the other substring in the same
way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
the current buffer.
The value is negative if the first substring is less, positive if
the first is greater, and zero if they are equal. The absolute
value of the result is one plus the index of the first differing
characters within the substrings.
This function ignores case when comparing characters if
`case-fold-search' is non-`nil'. It always ignores text
properties.
Suppose the current buffer contains the text `foobarbar
haha!rara!'; then in this example the two substrings are `rbar '
and `rara!'. The value is 2 because the first substring is greater
at the second character.
(compare-buffer-substrings nil 6 11 nil 16 21)
=> 2
File: elisp, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
Inserting Text
==============
"Insertion" means adding new text to a buffer. The inserted text
goes at point--between the character before point and the character
after point. Some insertion functions leave point before the inserted
text, while other functions leave it after. We call the former
insertion "after point" and the latter insertion "before point".
Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text (*note
Markers::). When a marker points at the place of insertion, insertion
may or may not relocate the marker, depending on the marker's insertion
type (*note Marker Insertion Types::). Certain special functions such
as `insert-before-markers' relocate all such markers to point after the
inserted text, regardless of the markers' insertion type.
Insertion functions signal an error if the current buffer is
read-only or if they insert within read-only text.
These functions copy text characters from strings and buffers along
with their properties. The inserted characters have exactly the same
properties as the characters they were copied from. By contrast,
characters specified as separate arguments, not part of a string or
buffer, inherit their text properties from the neighboring text.
The insertion functions convert text from unibyte to multibyte in
order to insert in a multibyte buffer, and vice versa--if the text
comes from a string or from a buffer. However, they do not convert
unibyte character codes 128 through 255 to multibyte characters, not
even if the current buffer is a multibyte buffer. *Note Converting
Representations::.
- Function: insert &rest args
This function inserts the strings and/or characters ARGS into the
current buffer, at point, moving point forward. In other words, it
inserts the text before point. An error is signaled unless all
ARGS are either strings or characters. The value is `nil'.
- Function: insert-before-markers &rest args
This function inserts the strings and/or characters ARGS into the
current buffer, at point, moving point forward. An error is
signaled unless all ARGS are either strings or characters. The
value is `nil'.
This function is unlike the other insertion functions in that it
relocates markers initially pointing at the insertion point, to
point after the inserted text. If an overlay begins the insertion
point, the inserted text falls outside the overlay; if a nonempty
overlay ends at the insertion point, the inserted text falls
inside that overlay.
- Function: insert-char character &optional count inherit
This function inserts COUNT instances of CHARACTER into the
current buffer before point. The argument COUNT should be a
number (`nil' means 1), and CHARACTER must be a character. The
value is `nil'.
This function does not convert unibyte character codes 128 through
255 to multibyte characters, not even if the current buffer is a
multibyte buffer. *Note Converting Representations::.
If INHERIT is non-`nil', then the inserted characters inherit
sticky text properties from the two characters before and after the
insertion point. *Note Sticky Properties::.
- Function: insert-buffer-substring from-buffer-or-name &optional
start end
This function inserts a portion of buffer FROM-BUFFER-OR-NAME
(which must already exist) into the current buffer before point.
The text inserted is the region from START and END. (These
arguments default to the beginning and end of the accessible
portion of that buffer.) This function returns `nil'.
In this example, the form is executed with buffer `bar' as the
current buffer. We assume that buffer `bar' is initially empty.
---------- Buffer: foo ----------
We hold these truths to be self-evident, that all
---------- Buffer: foo ----------
(insert-buffer-substring "foo" 1 20)
=> nil
---------- Buffer: bar ----------
We hold these truth-!-
---------- Buffer: bar ----------
*Note Sticky Properties::, for other insertion functions that inherit
text properties from the nearby text in addition to inserting it.
Whitespace inserted by indentation functions also inherits text
properties.
File: elisp, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
User-Level Insertion Commands
=============================
This section describes higher-level commands for inserting text,
commands intended primarily for the user but useful also in Lisp
programs.
- Command: insert-buffer from-buffer-or-name
This command inserts the entire contents of FROM-BUFFER-OR-NAME
(which must exist) into the current buffer after point. It leaves
the mark after the inserted text. The value is `nil'.
- Command: self-insert-command count
This command inserts the last character typed; it does so COUNT
times, before point, and returns `nil'. Most printing characters
are bound to this command. In routine use, `self-insert-command'
is the most frequently called function in Emacs, but programs
rarely use it except to install it on a keymap.
In an interactive call, COUNT is the numeric prefix argument.
This command calls `auto-fill-function' whenever that is non-`nil'
and the character inserted is in the table `auto-fill-chars'
(*note Auto Filling::).
This command performs abbrev expansion if Abbrev mode is enabled
and the inserted character does not have word-constituent syntax.
(*Note Abbrevs::, and *Note Syntax Class Table::.)
This is also responsible for calling `blink-paren-function' when
the inserted character has close parenthesis syntax (*note
Blinking::).
Do not try substituting your own definition of
`self-insert-command' for the standard one. The editor command
loop handles this function specially.
- Command: newline &optional number-of-newlines
This command inserts newlines into the current buffer before point.
If NUMBER-OF-NEWLINES is supplied, that many newline characters
are inserted.
This function calls `auto-fill-function' if the current column
number is greater than the value of `fill-column' and
NUMBER-OF-NEWLINES is `nil'. Typically what `auto-fill-function'
does is insert a newline; thus, the overall result in this case is
to insert two newlines at different places: one at point, and
another earlier in the line. `newline' does not auto-fill if
NUMBER-OF-NEWLINES is non-`nil'.
This command indents to the left margin if that is not zero.
*Note Margins::.
The value returned is `nil'. In an interactive call, COUNT is the
numeric prefix argument.
- Command: split-line
This command splits the current line, moving the portion of the
line after point down vertically so that it is on the next line
directly below where it was before. Whitespace is inserted as
needed at the beginning of the lower line, using the `indent-to'
function. `split-line' returns the position of point.
Programs hardly ever use this function.
- Variable: overwrite-mode
This variable controls whether overwrite mode is in effect. The
value should be `overwrite-mode-textual', `overwrite-mode-binary',
or `nil'. `overwrite-mode-textual' specifies textual overwrite
mode (treats newlines and tabs specially), and
`overwrite-mode-binary' specifies binary overwrite mode (treats
newlines and tabs like any other characters).
File: elisp, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
Deleting Text
=============
Deletion means removing part of the text in a buffer, without saving
it in the kill ring (*note The Kill Ring::). Deleted text can't be
yanked, but can be reinserted using the undo mechanism (*note Undo::).
Some deletion functions do save text in the kill ring in some special
cases.
All of the deletion functions operate on the current buffer, and all
return a value of `nil'.
- Command: erase-buffer
This function deletes the entire text of the current buffer,
leaving it empty. If the buffer is read-only, it signals a
`buffer-read-only' error; if some of the text in it is read-only,
it signals a `text-read-only' error. Otherwise, it deletes the
text without asking for any confirmation. It returns `nil'.
Normally, deleting a large amount of text from a buffer inhibits
further auto-saving of that buffer "because it has shrunk".
However, `erase-buffer' does not do this, the idea being that the
future text is not really related to the former text, and its size
should not be compared with that of the former text.
- Command: delete-region start end
This command deletes the text between positions START and END in
the current buffer, and returns `nil'. If point was inside the
deleted region, its value afterward is START. Otherwise, point
relocates with the surrounding text, as markers do.
- Function: delete-and-extract-region start end
This function deletes the text between positions START and END in
the current buffer, and returns a string containing the text just
deleted.
If point was inside the deleted region, its value afterward is
START. Otherwise, point relocates with the surrounding text, as
markers do.
- Command: delete-char count &optional killp
This command deletes COUNT characters directly after point, or
before point if COUNT is negative. If KILLP is non-`nil', then it
saves the deleted characters in the kill ring.
In an interactive call, COUNT is the numeric prefix argument, and
KILLP is the unprocessed prefix argument. Therefore, if a prefix
argument is supplied, the text is saved in the kill ring. If no
prefix argument is supplied, then one character is deleted, but
not saved in the kill ring.
The value returned is always `nil'.
- Command: delete-backward-char count &optional killp
This command deletes COUNT characters directly before point, or
after point if COUNT is negative. If KILLP is non-`nil', then it
saves the deleted characters in the kill ring.
In an interactive call, COUNT is the numeric prefix argument, and
KILLP is the unprocessed prefix argument. Therefore, if a prefix
argument is supplied, the text is saved in the kill ring. If no
prefix argument is supplied, then one character is deleted, but
not saved in the kill ring.
The value returned is always `nil'.
- Command: backward-delete-char-untabify count &optional killp
This command deletes COUNT characters backward, changing tabs into
spaces. When the next character to be deleted is a tab, it is
first replaced with the proper number of spaces to preserve
alignment and then one of those spaces is deleted instead of the
tab. If KILLP is non-`nil', then the command saves the deleted
characters in the kill ring.
Conversion of tabs to spaces happens only if COUNT is positive.
If it is negative, exactly -COUNT characters after point are
deleted.
In an interactive call, COUNT is the numeric prefix argument, and
KILLP is the unprocessed prefix argument. Therefore, if a prefix
argument is supplied, the text is saved in the kill ring. If no
prefix argument is supplied, then one character is deleted, but
not saved in the kill ring.
The value returned is always `nil'.
- User Option: backward-delete-char-untabify-method
This option specifies how `backward-delete-char-untabify' should
deal with whitespace. Possible values include `untabify', the
default, meaning convert a tab to many spaces and delete one;
`hungry', meaning delete all the whitespace characters before point
with one command, and `nil', meaning do nothing special for
whitespace characters.
File: elisp, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
User-Level Deletion Commands
============================
This section describes higher-level commands for deleting text,
commands intended primarily for the user but useful also in Lisp
programs.
- Command: delete-horizontal-space
This function deletes all spaces and tabs around point. It returns
`nil'.
In the following examples, we call `delete-horizontal-space' four
times, once on each line, with point between the second and third
characters on the line each time.
---------- Buffer: foo ----------
I -!-thought
I -!- thought
We-!- thought
Yo-!-u thought
---------- Buffer: foo ----------
(delete-horizontal-space) ; Four times.
=> nil
---------- Buffer: foo ----------
Ithought
Ithought
Wethought
You thought
---------- Buffer: foo ----------
- Command: delete-indentation &optional join-following-p
This function joins the line point is on to the previous line,
deleting any whitespace at the join and in some cases replacing it
with one space. If JOIN-FOLLOWING-P is non-`nil',
`delete-indentation' joins this line to the following line
instead. The function returns `nil'.
If there is a fill prefix, and the second of the lines being joined
starts with the prefix, then `delete-indentation' deletes the fill
prefix before joining the lines. *Note Margins::.
In the example below, point is located on the line starting
`events', and it makes no difference if there are trailing spaces
in the preceding line.
---------- Buffer: foo ----------
When in the course of human
-!- events, it becomes necessary
---------- Buffer: foo ----------
(delete-indentation)
=> nil
---------- Buffer: foo ----------
When in the course of human-!- events, it becomes necessary
---------- Buffer: foo ----------
After the lines are joined, the function `fixup-whitespace' is
responsible for deciding whether to leave a space at the junction.
- Function: fixup-whitespace
This function replaces all the whitespace surrounding point with
either one space or no space, according to the context. It
returns `nil'.
At the beginning or end of a line, the appropriate amount of space
is none. Before a character with close parenthesis syntax, or
after a character with open parenthesis or expression-prefix
syntax, no space is also appropriate. Otherwise, one space is
appropriate. *Note Syntax Class Table::.
In the example below, `fixup-whitespace' is called the first time
with point before the word `spaces' in the first line. For the
second invocation, point is directly after the `('.
---------- Buffer: foo ----------
This has too many -!-spaces
This has too many spaces at the start of (-!- this list)
---------- Buffer: foo ----------
(fixup-whitespace)
=> nil
(fixup-whitespace)
=> nil
---------- Buffer: foo ----------
This has too many spaces
This has too many spaces at the start of (this list)
---------- Buffer: foo ----------
- Command: just-one-space
This command replaces any spaces and tabs around point with a
single space. It returns `nil'.
- Command: delete-blank-lines
This function deletes blank lines surrounding point. If point is
on a blank line with one or more blank lines before or after it,
then all but one of them are deleted. If point is on an isolated
blank line, then it is deleted. If point is on a nonblank line,
the command deletes all blank lines following it.
A blank line is defined as a line containing only tabs and spaces.
`delete-blank-lines' returns `nil'.
File: elisp, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
The Kill Ring
=============
"Kill functions" delete text like the deletion functions, but save
it so that the user can reinsert it by "yanking". Most of these
functions have `kill-' in their name. By contrast, the functions whose
names start with `delete-' normally do not save text for yanking
(though they can still be undone); these are "deletion" functions.
Most of the kill commands are primarily for interactive use, and are
not described here. What we do describe are the functions provided for
use in writing such commands. You can use these functions to write
commands for killing text. When you need to delete text for internal
purposes within a Lisp function, you should normally use deletion
functions, so as not to disturb the kill ring contents. *Note
Deletion::.
Killed text is saved for later yanking in the "kill ring". This is
a list that holds a number of recent kills, not just the last text
kill. We call this a "ring" because yanking treats it as having
elements in a cyclic order. The list is kept in the variable
`kill-ring', and can be operated on with the usual functions for lists;
there are also specialized functions, described in this section, that
treat it as a ring.
Some people think this use of the word "kill" is unfortunate, since
it refers to operations that specifically _do not_ destroy the entities
"killed". This is in sharp contrast to ordinary life, in which death
is permanent and "killed" entities do not come back to life.
Therefore, other metaphors have been proposed. For example, the term
"cut ring" makes sense to people who, in pre-computer days, used
scissors and paste to cut up and rearrange manuscripts. However, it
would be difficult to change the terminology now.
* Menu:
* Kill Ring Concepts:: What text looks like in the kill ring.
* Kill Functions:: Functions that kill text.
* Yank Commands:: Commands that access the kill ring.
* Low-Level Kill Ring:: Functions and variables for kill ring access.
* Internals of Kill Ring:: Variables that hold kill-ring data.
File: elisp, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
Kill Ring Concepts
------------------
The kill ring records killed text as strings in a list, most recent
first. A short kill ring, for example, might look like this:
("some text" "a different piece of text" "even older text")
When the list reaches `kill-ring-max' entries in length, adding a new
entry automatically deletes the last entry.
When kill commands are interwoven with other commands, each kill
command makes a new entry in the kill ring. Multiple kill commands in
succession build up a single kill-ring entry, which would be yanked as a
unit; the second and subsequent consecutive kill commands add text to
the entry made by the first one.
For yanking, one entry in the kill ring is designated the "front" of
the ring. Some yank commands "rotate" the ring by designating a
different element as the "front." But this virtual rotation doesn't
change the list itself--the most recent entry always comes first in the
list.
File: elisp, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
Functions for Killing
---------------------
`kill-region' is the usual subroutine for killing text. Any command
that calls this function is a "kill command" (and should probably have
`kill' in its name). `kill-region' puts the newly killed text in a new
element at the beginning of the kill ring or adds it to the most recent
element. It determines automatically (using `last-command') whether
the previous command was a kill command, and if so appends the killed
text to the most recent entry.
- Command: kill-region start end
This function kills the text in the region defined by START and
END. The text is deleted but saved in the kill ring, along with
its text properties. The value is always `nil'.
In an interactive call, START and END are point and the mark.
If the buffer or text is read-only, `kill-region' modifies the kill
ring just the same, then signals an error without modifying the
buffer. This is convenient because it lets the user use a series
of kill commands to copy text from a read-only buffer into the
kill ring.
- User Option: kill-read-only-ok
If this option is non-`nil', `kill-region' does not signal an
error if the buffer or text is read-only. Instead, it simply
returns, updating the kill ring but not changing the buffer.
- Command: copy-region-as-kill start end
This command saves the region defined by START and END on the kill
ring (including text properties), but does not delete the text
from the buffer. It returns `nil'. It also indicates the extent
of the text copied by moving the cursor momentarily, or by
displaying a message in the echo area.
The command does not set `this-command' to `kill-region', so a
subsequent kill command does not append to the same kill ring
entry.
Don't call `copy-region-as-kill' in Lisp programs unless you aim to
support Emacs 18. For newer Emacs versions, it is better to use
`kill-new' or `kill-append' instead. *Note Low-Level Kill Ring::.
File: elisp, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
Functions for Yanking
---------------------
"Yanking" means reinserting an entry of previously killed text from
the kill ring. The text properties are copied too.
- Command: yank &optional arg
This command inserts before point the text in the first entry in
the kill ring. It positions the mark at the beginning of that
text, and point at the end.
If ARG is a list (which occurs interactively when the user types
`C-u' with no digits), then `yank' inserts the text as described
above, but puts point before the yanked text and puts the mark
after it.
If ARG is a number, then `yank' inserts the ARGth most recently
killed text--the ARGth element of the kill ring list.
`yank' does not alter the contents of the kill ring or rotate it.
It returns `nil'.
- Command: yank-pop arg
This command replaces the just-yanked entry from the kill ring
with a different entry from the kill ring.
This is allowed only immediately after a `yank' or another
`yank-pop'. At such a time, the region contains text that was just
inserted by yanking. `yank-pop' deletes that text and inserts in
its place a different piece of killed text. It does not add the
deleted text to the kill ring, since it is already in the kill
ring somewhere.
If ARG is `nil', then the replacement text is the previous element
of the kill ring. If ARG is numeric, the replacement is the ARGth
previous kill. If ARG is negative, a more recent kill is the
replacement.
The sequence of kills in the kill ring wraps around, so that after
the oldest one comes the newest one, and before the newest one
goes the oldest.
The return value is always `nil'.
File: elisp, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
Low-Level Kill Ring
-------------------
These functions and variables provide access to the kill ring at a
lower level, but still convenient for use in Lisp programs, because they
take care of interaction with window system selections (*note Window
System Selections::).
- Function: current-kill n &optional do-not-move
The function `current-kill' rotates the yanking pointer, which
designates the "front" of the kill ring, by N places (from newer
kills to older ones), and returns the text at that place in the
ring.
If the optional second argument DO-NOT-MOVE is non-`nil', then
`current-kill' doesn't alter the yanking pointer; it just returns
the Nth kill, counting from the current yanking pointer.
If N is zero, indicating a request for the latest kill,
`current-kill' calls the value of `interprogram-paste-function'
(documented below) before consulting the kill ring.
- Function: kill-new string
This function puts the text STRING into the kill ring as a new
entry at the front of the ring. It discards the oldest entry if
appropriate. It also invokes the value of
`interprogram-cut-function' (see below).
- Function: kill-append string before-p
This function appends the text STRING to the first entry in the
kill ring. Normally STRING goes at the end of the entry, but if
BEFORE-P is non-`nil', it goes at the beginning. This function
also invokes the value of `interprogram-cut-function' (see below).
- Variable: interprogram-paste-function
This variable provides a way of transferring killed text from other
programs, when you are using a window system. Its value should be
`nil' or a function of no arguments.
If the value is a function, `current-kill' calls it to get the
"most recent kill". If the function returns a non-`nil' value,
then that value is used as the "most recent kill". If it returns
`nil', then the first element of `kill-ring' is used.
The normal use of this hook is to get the window system's primary
selection as the most recent kill, even if the selection belongs to
another application. *Note Window System Selections::.
- Variable: interprogram-cut-function
This variable provides a way of communicating killed text to other
programs, when you are using a window system. Its value should be
`nil' or a function of one argument.
If the value is a function, `kill-new' and `kill-append' call it
with the new first element of the kill ring as an argument.
The normal use of this hook is to set the window system's primary
selection from the newly killed text. *Note Window System
Selections::.
File: elisp, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
Internals of the Kill Ring
--------------------------
The variable `kill-ring' holds the kill ring contents, in the form
of a list of strings. The most recent kill is always at the front of
the list.
The `kill-ring-yank-pointer' variable points to a link in the kill
ring list, whose CAR is the text to yank next. We say it identifies
the "front" of the ring. Moving `kill-ring-yank-pointer' to a
different link is called "rotating the kill ring". We call the kill
ring a "ring" because the functions that move the yank pointer wrap
around from the end of the list to the beginning, or vice-versa.
Rotation of the kill ring is virtual; it does not change the value of
`kill-ring'.
Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
whose values are normally lists. The word "pointer" in the name of the
`kill-ring-yank-pointer' indicates that the variable's purpose is to
identify one element of the list for use by the next yank command.
The value of `kill-ring-yank-pointer' is always `eq' to one of the
links in the kill ring list. The element it identifies is the CAR of
that link. Kill commands, which change the kill ring, also set this
variable to the value of `kill-ring'. The effect is to rotate the ring
so that the newly killed text is at the front.
Here is a diagram that shows the variable `kill-ring-yank-pointer'
pointing to the second entry in the kill ring `("some text" "a
different piece of text" "yet older text")'.
kill-ring ---- kill-ring-yank-pointer
| |
| v
| --- --- --- --- --- ---
--> | | |------> | | |--> | | |--> nil
--- --- --- --- --- ---
| | |
| | |
| | -->"yet older text"
| |
| --> "a different piece of text"
|
--> "some text"
This state of affairs might occur after `C-y' (`yank') immediately
followed by `M-y' (`yank-pop').
- Variable: kill-ring
This variable holds the list of killed text sequences, most
recently killed first.
- Variable: kill-ring-yank-pointer
This variable's value indicates which element of the kill ring is
at the "front" of the ring for yanking. More precisely, the value
is a tail of the value of `kill-ring', and its CAR is the kill
string that `C-y' should yank.
- User Option: kill-ring-max
The value of this variable is the maximum length to which the kill
ring can grow, before elements are thrown away at the end. The
default value for `kill-ring-max' is 30.
File: elisp, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
Undo
====
Most buffers have an "undo list", which records all changes made to
the buffer's text so that they can be undone. (The buffers that don't
have one are usually special-purpose buffers for which Emacs assumes
that undoing is not useful.) All the primitives that modify the text
in the buffer automatically add elements to the front of the undo list,
which is in the variable `buffer-undo-list'.
- Variable: buffer-undo-list
This variable's value is the undo list of the current buffer. A
value of `t' disables the recording of undo information.
Here are the kinds of elements an undo list can have:
`POSITION'
This kind of element records a previous value of point; undoing
this element moves point to POSITION. Ordinary cursor motion does
not make any sort of undo record, but deletion operations use
these entries to record where point was before the command.
`(BEG . END)'
This kind of element indicates how to delete text that was
inserted. Upon insertion, the text occupied the range BEG-END in
the buffer.
`(TEXT . POSITION)'
This kind of element indicates how to reinsert text that was
deleted. The deleted text itself is the string TEXT. The place to
reinsert it is `(abs POSITION)'.
`(t HIGH . LOW)'
This kind of element indicates that an unmodified buffer became
modified. The elements HIGH and LOW are two integers, each
recording 16 bits of the visited file's modification time as of
when it was previously visited or saved. `primitive-undo' uses
those values to determine whether to mark the buffer as unmodified
once again; it does so only if the file's modification time
matches those numbers.
`(nil PROPERTY VALUE BEG . END)'
This kind of element records a change in a text property. Here's
how you might undo the change:
(put-text-property BEG END PROPERTY VALUE)
`(MARKER . ADJUSTMENT)'
This kind of element records the fact that the marker MARKER was
relocated due to deletion of surrounding text, and that it moved
ADJUSTMENT character positions. Undoing this element moves MARKER
- ADJUSTMENT characters.
`nil'
This element is a boundary. The elements between two boundaries
are called a "change group"; normally, each change group
corresponds to one keyboard command, and undo commands normally
undo an entire group as a unit.
- Function: undo-boundary
This function places a boundary element in the undo list. The undo
command stops at such a boundary, and successive undo commands undo
to earlier and earlier boundaries. This function returns `nil'.
The editor command loop automatically creates an undo boundary
before each key sequence is executed. Thus, each undo normally
undoes the effects of one command. Self-inserting input
characters are an exception. The command loop makes a boundary
for the first such character; the next 19 consecutive
self-inserting input characters do not make boundaries, and then
the 20th does, and so on as long as self-inserting characters
continue.
All buffer modifications add a boundary whenever the previous
undoable change was made in some other buffer. This is to ensure
that each command makes a boundary in each buffer where it makes
changes.
Calling this function explicitly is useful for splitting the
effects of a command into more than one unit. For example,
`query-replace' calls `undo-boundary' after each replacement, so
that the user can undo individual replacements one by one.
- Function: primitive-undo count list
This is the basic function for undoing elements of an undo list.
It undoes the first COUNT elements of LIST, returning the rest of
LIST. You could write this function in Lisp, but it is convenient
to have it in C.
`primitive-undo' adds elements to the buffer's undo list when it
changes the buffer. Undo commands avoid confusion by saving the
undo list value at the beginning of a sequence of undo operations.
Then the undo operations use and update the saved value. The new
elements added by undoing are not part of this saved value, so
they don't interfere with continuing to undo.
File: elisp, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
Maintaining Undo Lists
======================
This section describes how to enable and disable undo information for
a given buffer. It also explains how the undo list is truncated
automatically so it doesn't get too big.
Recording of undo information in a newly created buffer is normally
enabled to start with; but if the buffer name starts with a space, the
undo recording is initially disabled. You can explicitly enable or
disable undo recording with the following two functions, or by setting
`buffer-undo-list' yourself.
- Command: buffer-enable-undo &optional buffer-or-name
This command enables recording undo information for buffer
BUFFER-OR-NAME, so that subsequent changes can be undone. If no
argument is supplied, then the current buffer is used. This
function does nothing if undo recording is already enabled in the
buffer. It returns `nil'.
In an interactive call, BUFFER-OR-NAME is the current buffer. You
cannot specify any other buffer.
- Command: buffer-disable-undo &optional buffer
- Command: buffer-flush-undo &optional buffer
This function discards the undo list of BUFFER, and disables
further recording of undo information. As a result, it is no
longer possible to undo either previous changes or any subsequent
changes. If the undo list of BUFFER is already disabled, this
function has no effect.
This function returns `nil'.
The name `buffer-flush-undo' is not considered obsolete, but the
preferred name is `buffer-disable-undo'.
As editing continues, undo lists get longer and longer. To prevent
them from using up all available memory space, garbage collection trims
them back to size limits you can set. (For this purpose, the "size" of
an undo list measures the cons cells that make up the list, plus the
strings of deleted text.) Two variables control the range of acceptable
sizes: `undo-limit' and `undo-strong-limit'.
- Variable: undo-limit
This is the soft limit for the acceptable size of an undo list.
The change group at which this size is exceeded is the last one
kept.
- Variable: undo-strong-limit
This is the upper limit for the acceptable size of an undo list.
The change group at which this size is exceeded is discarded
itself (along with all older change groups). There is one
exception: the very latest change group is never discarded no
matter how big it is.
File: elisp, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
Filling
=======
"Filling" means adjusting the lengths of lines (by moving the line
breaks) so that they are nearly (but no greater than) a specified
maximum width. Additionally, lines can be "justified", which means
inserting spaces to make the left and/or right margins line up
precisely. The width is controlled by the variable `fill-column'. For
ease of reading, lines should be no longer than 70 or so columns.
You can use Auto Fill mode (*note Auto Filling::) to fill text
automatically as you insert it, but changes to existing text may leave
it improperly filled. Then you must fill the text explicitly.
Most of the commands in this section return values that are not
meaningful. All the functions that do filling take note of the current
left margin, current right margin, and current justification style
(*note Margins::). If the current justification style is `none', the
filling functions don't actually do anything.
Several of the filling functions have an argument JUSTIFY. If it is
non-`nil', that requests some kind of justification. It can be `left',
`right', `full', or `center', to request a specific style of
justification. If it is `t', that means to use the current
justification style for this part of the text (see
`current-justification', below). Any other value is treated as `full'.
When you call the filling functions interactively, using a prefix
argument implies the value `full' for JUSTIFY.
- Command: fill-paragraph justify
This command fills the paragraph at or after point. If JUSTIFY is
non-`nil', each line is justified as well. It uses the ordinary
paragraph motion commands to find paragraph boundaries. *Note
Paragraphs: (emacs)Paragraphs.
- Command: fill-region start end &optional justify nosqueeze to-eop
This command fills each of the paragraphs in the region from START
to END. It justifies as well if JUSTIFY is non-`nil'.
If NOSQUEEZE is non-`nil', that means to leave whitespace other
than line breaks untouched. If TO-EOP is non-`nil', that means to
keep filling to the end of the paragraph--or the next hard
newline, if `use-hard-newlines' is enabled (see below).
The variable `paragraph-separate' controls how to distinguish
paragraphs. *Note Standard Regexps::.
- Command: fill-individual-paragraphs start end &optional justify
citation-regexp
This command fills each paragraph in the region according to its
individual fill prefix. Thus, if the lines of a paragraph were
indented with spaces, the filled paragraph will remain indented in
the same fashion.
The first two arguments, START and END, are the beginning and end
of the region to be filled. The third and fourth arguments,
JUSTIFY and CITATION-REGEXP, are optional. If JUSTIFY is
non-`nil', the paragraphs are justified as well as filled. If
CITATION-REGEXP is non-`nil', it means the function is operating
on a mail message and therefore should not fill the header lines.
If CITATION-REGEXP is a string, it is used as a regular
expression; if it matches the beginning of a line, that line is
treated as a citation marker.
Ordinarily, `fill-individual-paragraphs' regards each change in
indentation as starting a new paragraph. If
`fill-individual-varying-indent' is non-`nil', then only separator
lines separate paragraphs. That mode can handle indented
paragraphs with additional indentation on the first line.
- User Option: fill-individual-varying-indent
This variable alters the action of `fill-individual-paragraphs' as
described above.
- Command: fill-region-as-paragraph start end &optional justify
nosqueeze squeeze-after
This command considers a region of text as a single paragraph and
fills it. If the region was made up of many paragraphs, the blank
lines between paragraphs are removed. This function justifies as
well as filling when JUSTIFY is non-`nil'.
In an interactive call, any prefix argument requests justification.
If NOSQUEEZE is non-`nil', that means to leave whitespace other
than line breaks untouched. If SQUEEZE-AFTER is non-`nil', it
specifies a position in the region, and means don't canonicalize
spaces before that position.
In Adaptive Fill mode, this command calls `fill-context-prefix' to
choose a fill prefix by default. *Note Adaptive Fill::.
- Command: justify-current-line &optional how eop nosqueeze
This command inserts spaces between the words of the current line
so that the line ends exactly at `fill-column'. It returns `nil'.
The argument HOW, if non-`nil' specifies explicitly the style of
justification. It can be `left', `right', `full', `center', or
`none'. If it is `t', that means to do follow specified
justification style (see `current-justification', below). `nil'
means to do full justification.
If EOP is non-`nil', that means do left-justification if
`current-justification' specifies full justification. This is used
for the last line of a paragraph; even if the paragraph as a whole
is fully justified, the last line should not be.
If NOSQUEEZE is non-`nil', that means do not change interior
whitespace.
- User Option: default-justification
This variable's value specifies the style of justification to use
for text that doesn't specify a style with a text property. The
possible values are `left', `right', `full', `center', or `none'.
The default value is `left'.
- Function: current-justification
This function returns the proper justification style to use for
filling the text around point.
- User Option: sentence-end-double-space
If this variable is non-`nil', a period followed by just one space
does not count as the end of a sentence, and the filling functions
avoid breaking the line at such a place.
- Variable: fill-paragraph-function
This variable provides a way for major modes to override the
filling of paragraphs. If the value is non-`nil',
`fill-paragraph' calls this function to do the work. If the
function returns a non-`nil' value, `fill-paragraph' assumes the
job is done, and immediately returns that value.
The usual use of this feature is to fill comments in programming
language modes. If the function needs to fill a paragraph in the
usual way, it can do so as follows:
(let ((fill-paragraph-function nil))
(fill-paragraph arg))
- Variable: use-hard-newlines
If this variable is non-`nil', the filling functions do not delete
newlines that have the `hard' text property. These "hard
newlines" act as paragraph separators.
File: elisp, Node: Margins, Next: Adaptive Fill, Prev: Filling, Up: Text
Margins for Filling
===================
- User Option: fill-prefix
This buffer-local variable specifies a string of text that appears
at the beginning of normal text lines and should be disregarded
when filling them. Any line that fails to start with the fill
prefix is considered the start of a paragraph; so is any line that
starts with the fill prefix followed by additional whitespace.
Lines that start with the fill prefix but no additional whitespace
are ordinary text lines that can be filled together. The
resulting filled lines also start with the fill prefix.
The fill prefix follows the left margin whitespace, if any.
- User Option: fill-column
This buffer-local variable specifies the maximum width of filled
lines. Its value should be an integer, which is a number of
columns. All the filling, justification, and centering commands
are affected by this variable, including Auto Fill mode (*note
Auto Filling::).
As a practical matter, if you are writing text for other people to
read, you should set `fill-column' to no more than 70. Otherwise
the line will be too long for people to read comfortably, and this
can make the text seem clumsy.
- Variable: default-fill-column
The value of this variable is the default value for `fill-column'
in buffers that do not override it. This is the same as
`(default-value 'fill-column)'.
The default value for `default-fill-column' is 70.
- Command: set-left-margin from to margin
This sets the `left-margin' property on the text from FROM to TO
to the value MARGIN. If Auto Fill mode is enabled, this command
also refills the region to fit the new margin.
- Command: set-right-margin from to margin
This sets the `right-margin' property on the text from FROM to TO
to the value MARGIN. If Auto Fill mode is enabled, this command
also refills the region to fit the new margin.
- Function: current-left-margin
This function returns the proper left margin value to use for
filling the text around point. The value is the sum of the
`left-margin' property of the character at the start of the
current line (or zero if none), and the value of the variable
`left-margin'.
- Function: current-fill-column
This function returns the proper fill column value to use for
filling the text around point. The value is the value of the
`fill-column' variable, minus the value of the `right-margin'
property of the character after point.
- Command: move-to-left-margin &optional n force
This function moves point to the left margin of the current line.
The column moved to is determined by calling the function
`current-left-margin'. If the argument N is non-`nil',
`move-to-left-margin' moves forward N-1 lines first.
If FORCE is non-`nil', that says to fix the line's indentation if
that doesn't match the left margin value.
- Function: delete-to-left-margin &optional from to
This function removes left margin indentation from the text between
FROM and TO. The amount of indentation to delete is determined by
calling `current-left-margin'. In no case does this function
delete non-whitespace. If FROM and TO are omitted, they default
to the whole buffer.
- Function: indent-to-left-margin
This is the default `indent-line-function', used in Fundamental
mode, Text mode, etc. Its effect is to adjust the indentation at
the beginning of the current line to the value specified by the
variable `left-margin'. This may involve either inserting or
deleting whitespace.
- Variable: left-margin
This variable specifies the base left margin column. In
Fundamental mode, `C-j' indents to this column. This variable
automatically becomes buffer-local when set in any fashion.
- Variable: fill-nobreak-predicate
This variable gives major modes a way to specify not to break a
line at certain places. Its value should be a function. This
function is called during filling, with no arguments and with
point located at the place where a break is being considered. If
the function returns non-`nil', then the line won't be broken
there.